---
id: pinFile
title: ''
---

## URL
```
https://<endpoint-api-host>/pinning/pinFile
```

例如，“Decoo 上海” 的 *pinFile* API URL 为：
```
https://api-sh.decoo-cloud.cn/pinning/pinFile
```

## 描述
通过 Endpoint 上传文件到 Decoo Cloud 并存储到 IPFS 网络。

:::note
为了提供和 [pinByHash](pinning/pin-by-hash.mdx) 一致的编程模型，每次调用 *pinFile* 时也会自动生成一个*pin job*。同样地，您也可以调用 [pinJobs](pinning/pin-jobs.mdx) API 来查询这些 *pin job* 的状态。
:::

## 请求类型
POST

## Headers
```
"UserAccessToken": "<YOUR_ACCESS_TOKEN>"
```

## Body
API 请求的 Body 应该为 *multipart/form-data* 格式，并包含以下键值对：

**file**<br/>
表单中的第一个 Key 应该为 “file”，Value 为要上传的文件。
  
**decooMetadata (Optional)**

在上传文件的同时，可以附加一些 metadata。这些 metadata 可以在调用 [pinList](pinning/pin-list.mdx) 查询文件列表时做为过滤条件。

*decooMetadata* 格式如下:
```json
{
  "name": "<自定义文件名。如果不提供，则默认使用原文件名 (如果能获取到的话)。>"
}
```

*decooMetadata* 示例如下:
```json
"decooOptions": {
  "name": "我的文件"
}
```

**cid**<br/>

待上传文件的 IPFS CID。您可以通过多种方式获取一个文件的 CID，比如：

- IPFS Desktop。本地安装 [IPFS Desktop](https://docs.ipfs.io/install/ipfs-desktop) 或者 [go-ipfs](https://github.com/ipfs/go-ipfs)，然后调用本地 IPFS 节点的 [/api/v0/add](https://docs.ipfs.io/reference/http/api/#api-v0-add) HTTP API 来获取文件的 CID (注意：在调用该 API 时，建议将 *only-hash* 参数设为 true)。
- ipfs-core。通过 [ipfs-core](https://www.npmjs.com/package/ipfs-core) 来获取文件 CID。
- Decoo SDK。直接使用 Decoo 提供的 [Decoo SDK](https://www.npmjs.com/package/@decooio/sdk) 来获取文件 CID。

**secret**<br/>

用户使用自己的 RSA 私钥针对文件 CID 生成的签名。详情可参考 [API 认证机制](/general/pinningWithApi#数字签名) 的相关部分。

## Response
```json
{
  "PinHash": "<上传文件的 IPFS CID>",
  "PinSize": "<文件大小 (字节)>",
  "PinDate": "<文件存储到 IPFS 的时间戳 (ISO 8601格式)>"
}
```

## Curl 请求示例
```sh
curl -X POST "https://api-sh.decoo-cloud.cn/pinning/pinFile" \
  -H "UserAccessToken: <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@<YOUR_FILE_PATH>" \
  -F 'decooMetadata="{\"name\": \"我的文件\"}"' \
  -F "cid=<YOUR_FILE_CID>" \
  -F "secret=<YOUR_DIGITITAL_SIGNATURE>"
```
